Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / cmds.fmt / dvips.man < prev next >

Wrap

Text File | 1991-01-15 | 30.5 KB | 793 lines

DVIPS User Commands DVIPS NNAAMMEE dvips - convert a TeX DVI file to POSTSCRIPT SSYYNNOOPPSSIISS ddvviippss [ --cc _n_u_m ] [ --dd _n_u_m ] [ --ee _n_u_m ] [ --ff ] [ --hh _f_i_l_e ] [ --ll _n_u_m ] [ --mm ] [ --nn _n_u_m ] [ --oo _f_i_l_e ] [ --pp _n_u_m ] [ --qq ] [ --rr ] [ --ss ] [ --tt _m_o_d_e_n_a_m_e ] [ --xx _n_u_m ] [ --CC _n_u_m ] [ --DD _n_u_m ] [ --FF ] [ --KK ] [ --MM ] [ --NN ] [ --PP _p_r_i_n_t_e_r_n_a_m_e ] [ --UU ] [ --XX _n_u_m ] [ --YY _n_u_m ] [ --ZZ ] [ --?? ] _f_i_l_e[.dvi] DDEESSCCRRIIPPTTIIOONN The program ddvviippss converts a DVI file _f_i_l_e[.dvi] produced by TeX (or by some other processor like GFtoDVI) and converts it to POSTSCRIPT, normally sending the result directly to the laserprinter. The DVI file may be specified without the ._d_v_i extension. Fonts used may either be resident in the printer or defined as bitmaps in PK files, or a `virtual' combination of both. If the MMaakkeeTTeeXXPPKK program is installed, ddvviippss will automatically invoke METAFONT to generate fonts that don't already exist. OOPPTTIIOONNSS Boolean flags that are turned on by certain letters (such as -r to reverse pages) can be turned off by following the option immediately with a 0 (as in -r0). The options that this can be used with are ffmmqqrrFFKKNNUUZZ. The command line switches are: --cc _n_u_m Generate _n_u_m copies of every page. Default is 1. (For collated copies, see the --CC option below.) --dd _n_u_m Set the debug flags. This is intended only for emer- gencies or for unusual fact-finding expeditions; it will work only if ddvviippss has been compiled with the DEBUG option. The file _d_e_b_u_g._h in the sources indi- cates what the values of _n_u_m can be. Use a value of -1 for maximum output. --ee _n_u_m Make sure that each character is placed at most this many pixels from its `true' resolution-independent position on the page. The default value of this parame- ter is resolution dependent (it is the number of entries in the list [100, 200, 300, 400, 500, 600, 800, 1000, 1200, 1600, 2000, 2400, 2800, 3200, ...] that are less than or equal to the resolution in dots per inch). Allowing individual characters to `drift' from their correctly rounded positions by a few pixels, while regaining the true position at the beginning of each new word, improves the spacing of letters in words. TeXware 9 August 1990 1 DVIPS User Commands DVIPS --ff Run as a filter. Read the DVI file from standard input and write the POSTSCRIPT to standard output. The stan- dard input must be seekable, so it cannot be a pipe. If you must use a pipe, write a shell script that copies the pipe output to a temporary file and then points dvips at this file. --hh _n_a_m_e Prepend file _n_a_m_e as an additional header file. (How- ever, if the name is simply `-', suppress all header files from the output.) This header file gets added to the POSTSCRIPT userdict. --ll _n_u_m The last page printed will be the first one numbered _n_u_m. Default is the last page in the document. --mm Specify manual feed for printer. --nn _n_u_m At most _n_u_m pages will be printed out. Default is 100000. --oo _n_a_m_e The output will be sent to file _n_a_m_e. If no file name is given, the default name is _f_i_l_e.ps; if this option isn't given, the default name is !lpr. If the first character of the file name is an exclamation mark, then the remainder will be used as an argument to popen; thus, specifying !lpr as the output file will automati- cally queue the file for printing. --pp _n_u_m The first page printed will be the first one numbered _n_u_m. Default is the first page in the document. --qq Run in quiet mode. Don't chatter about pages con- verted, etc.; report nothing but errors to stderr. --rr Stack pages in reverse order. Normally, page one will be printed first. --ss Causes the entire global output to be enclosed in a save/restore pair. This causes the file to not be truly conformant, and is thus not recommended, but is useful if you are driving the printer directly and don't care too much about the portability of the out- put. --tt _m_o_d_e_n_a_m_e This sets the mode to _m_o_d_e_n_a_m_e. Currently, the only modes allowable are: lleetttteerr, which selects _l_e_t_t_e_r size TeXware 9 August 1990 2 DVIPS User Commands DVIPS (8.5 by 11 inch page); aa33, which selects _a_3 size; aa44, which selects _a_4 size; lleeggaall, which selects _l_e_g_a_l size (8.5 by 14 inches); lleeddggeerr, which selects _l_e_g_a_l size (11 by 17 inches); llaannddssccaappee, which rotates the docu- ment by ninety degrees. The default page size is _l_e_t_t_e_r. The llaannddssccaappee option may be combined with any of the others; doing so requires giving the --tt option twice. The upper left corner of each page in the DVI file is placed one inch from the left and one inch from the top. --xx _n_u_m Set the magnification ratio to _n_u_m /1000. Overrides the magnification specified in the DVI file. Must be between 10 and 100000. --CC _n_u_m Create _n_u_m copies, but collated (by replicating the data in the POSTSCRIPT file). Slower than the --cc option, but easier on the humans. --DD _n_u_m Set the resolution in dpi (dots per inch) to _n_u_m. This affects the choice of bitmap fonts that are loaded and also the positioning of letters in resident POSTSCRIPT fonts. Must be between 10 and 10000. This affects both the horizontal and vertical resolution. --FF Causes control-D (ASCII code 4) to be appended as the very last character of the POSTSCRIPT file. This is useful when ddvviippss is driving the printer directly, as is common on extremely small systems, instead of work- ing through a spooler. --KK Removes comments from included graphics files. Only necessary when using brain-damaged spoolers or POSTSCRIPT postprocessors that don't properly interpret structured comments. --MM Turns off the automatic font generation capability. --NN Turns off structured comments; this might be necessary on some systems that try to interpret POSTSCRIPT com- ments in weird ways, or on some POSTSCRIPT printers. --PP _p_r_i_n_t_e_r_n_a_m_e Sets up the output for the appropriate printer. This is implemented by reading in _c_o_n_f_i_g._p_r_i_n_t_e_r_n_a_m_e, which can then set the output pipe (as in, o !lpr -Pprinter- name) as well as the font paths and any other defaults for that printer only. It is recommended that all standard defaults go in the one master _c_o_n_f_i_g._p_s file TeXware 9 August 1990 3 DVIPS User Commands DVIPS and only things that vary printer to printer go in the _c_o_n_f_i_g._p_r_i_n_t_e_r_n_a_m_e files. Note that _c_o_n_f_i_g._p_s is read before _c_o_n_f_i_g._p_r_i_n_t_e_r_n_a_m_e. In addition, another file called ~/._d_v_i_p_s_r_c is searched for immediately after _c_o_n_f_i_g._p_s; this file is intended for user defaults. If no --PP command is given, the environment variable PPRRIINNTTEERR is checked. If that variable exists, and a corresponding _c_o_n_f_i_g.PPRRIINNTTEERR exists, then that confi- guration file is read in. --UU Turns off a virtual memory saving optimization that triggers a bug in the Xerox 4045 POSTSCRIPT inter- preter; not recommended unless you must generate output to this printer. --XX _n_u_m Set the horizontal resolution in dpi (dots per inch) to _n_u_m. --YY _n_u_m Set the vertical resolution in dpi (dots per inch) to _n_u_m. --ZZ Causes bitmap fonts to be compressed before they are downloaded, thereby reducing the size of the POSTSCRIPT font-downloading information. Especially useful at high resolutions or when very large fonts are used. Will slow down printing somewhat, especially on early 68000-based POSTSCRIPT printers. --?? Print out the banner identifying the program. CCOONNFFIIGG FFIILLEE OOPPTTIIOONNSS The file _c_o_n_f_i_g._p_s (and the user's own ~/._d_v_i_p_s_r_c) can be used to set many of the options to configure ddvviippss for a particular site and printer. These will probably be set up by the installer, so normal users can skip this section. The name and location of the config file can be changed at installation time. The environment variable TTEEXXCCOONNFFIIGG (if it exists) is used as the path to configuration files. Each line of the file specifies a configuration option. If the initial character is a space, an asterisk, a pound sign, or a semicolon, the line is ignored. But if the initial char- acter is an option like "o", for example, the remainder of the line is considered to be a parameter. The options are: ee _n_u_m Sets the maximum drift parameter to _n_u_m dots (pixels) as explained above. ff Run as a filter by default. TeXware 9 August 1990 4 DVIPS User Commands DVIPS hh _n_a_m_e Add _n_a_m_e as a POSTSCRIPT header file to be downloaded at the beginning. mm _n_u_m _n_u_m is the virtual memory available for fonts and strings in the printer. Default is 180000. oo _n_a_m_e The default output file is set to _n_a_m_e. As above, it can be a pipe. pp _n_a_m_e Sets the name of the file to read for PostScript font mapping. This file name defaults to psfonts.map, but can be changed in the printer configuration file to allow different printers to have different sets of PostScript fonts. qq Run in quiet mode by default. rr Reverse the order of pages by default. ss Enclose the entire document in a global save/restore pair by default. Not recommended, but useful in some environments; this breaks the `conformance' of the document. tt _m_o_d_e_n_a_m_e This sets the mode to _m_o_d_e_n_a_m_e. Currently, the only modes allowable are: lleetttteerr, which selects _l_e_t_t_e_r size (8.5 by 11 inch page); aa44, which selects _a_4 size; lleeggaall, which selects _l_e_g_a_l size (8.5 by 14 inches); llaannddssccaappee, which rotates a _l_e_t_t_e_r size document by ninety degrees. The default mode is _l_e_t_t_e_r. The upper left corner of each page in the DVI file is placed one inch from the left and one inch from the top. The --tt _m_o_d_e_n_a_m_e option will override this. DD _n_u_m Sets the vertical and horizontal resolution to _n_u_m dots per inch (dpi). EE _c_o_m_m_a_n_d Executes the command listed; can be used to get the current date into a header file for inclusion, for instance. Possibly dangerous; in many installations this may be disabled, in which case a warning message will be printed if the option is used. HH _p_a_t_h The (colon-separated) path to search for POSTSCRIPT TeXware 9 August 1990 5 DVIPS User Commands DVIPS header files is _p_a_t_h. KK Removes POSTSCRIPT comments from included POSTSCRIPT graphics files. MM _m_o_d_e Set _m_o_d_e as the METAFONT mode to be used when generat- ing fonts. This is passed along to MakeTeXPK and over- rides mode derivation from the base resolution. NN Disable POSTSCRIPT comments by default. PP _p_a_t_h The (colon-separated) path to search for bitmap (PK) font files is _p_a_t_h. The TEXPKS environment variable will override this. If a % character is found in _p_a_t_h, the following substitutions will be made, and then a search will be made for the resulting filenames. A %f is replaced by the font name. A %d is replaced by the font size in dots per inch (dpi). A %p is replaced by the font family. This is always "pk". A %m is replaced by the font mode. This is the _m_o_d_e given in the MM option. RR _n_u_m _n_u_m ... Sets up a list of default resolutions to search for PK fonts, if the requested size is not available. The output will then scale the font found using POSTSCRIPT scaling to the requested size. Note that the resultant output will be ugly, and thus a warning is issued. To turn this off, simply don't use such a line in the con- figuration file. SS _p_a_t_h The (colon-separated) path to search for special illus- trations (encapsulated POSTSCRIPT files or psfiles) is _p_a_t_h. The TEXINPUTS environment variable will override this. TT _p_a_t_h The (colon-separated) path to search for the tfm files is _p_a_t_h. The TEXFONTS environment variable will over- ride this. This path is used for resident fonts and fonts that can't be otherwise found. It's usually best to make it identical to the path used by TeX. UU Turns off a memory-saving optimization; see the command line option for more information. VV _p_a_t_h The (colon-separated) path to search for virtual font (VF) files is _p_a_t_h. This may be device-dependent, if TeXware 9 August 1990 6 DVIPS User Commands DVIPS you use virtual fonts to simulate actual fonts on dif- ferent devices. WW _s_t_r_i_n_g Sends _s_t_r_i_n_g to stderr, if it exists; otherwise it can- cels another previous message. This is useful in the default configuration file if you want to require the user to specify a printer, for instance, or if you want to notify the user that the resultant output has spe- cial characteristics. XX _n_u_m Sets the horizontal resolution to _n_u_m dots per inch (dpi). YY _n_u_m Sets the vertical resolution to _n_u_m dots per inch (dpi). ZZ Compress all downloaded fonts by default. PPAATTHH IINNTTEERRPPRREETTAATTIIOONN All paths variables are the names of directories (path ele- ments), separated by colons. Each path element can be either the literal name of a directory or one of the ~ forms common under Unix. If a path element is a single tilde, it is replaced by the contents of the environment variable HOME, which is normally set to the user's home directory. If the path element is a tilde followed by anything, the part after the tilde is interpreted as a user name, and his home directory is fetched from the system password file and used as the real path element. Where environment variables can override paths, an addi- tional path element form is allowed. If a path element is the empty string, it is replaced with the system defaults. Thus, to say (with an environment variable) to search the user's home directory, followed by the system default paths, the following command would be used: setenv TEXINPUTS ~: This is a path of two elements. The first is the user's home directory. The second path element is the empty string, indicating that the system defaults should be searched. PPOOSSTTSSCCRRIIPPTT FFOONNTT SSUUPPPPOORRTT This version of dvips supports POSTSCRIPT fonts. You need TFM (TeX Font Metric) files for all fonts seen by TeX; they can be generated from AFM (Adobe Font Metric) files by run- ning the program aaffmm22ttffmm (which is described on its own TeXware 9 August 1990 7 DVIPS User Commands DVIPS manual page). That program also creates virtual fonts with which you can use normal plain TeX conventions. The set of all resident fonts known to ddvviippss appears in the file _p_s_f_o_n_t_s._m_a_p, which should be updated whenever you install a new resident font. See aaffmm22ttffmm for examples and more infor- mation on this file. \\ssppeecciiaall OOPPTTIIOONNSS This DVI driver allows the inclusion of POSTSCRIPT code to be inserted in a TeX file via TeX's \special command. For compatibility with other systems, several different conven- tions are supported. First, there's a flexible key-and-value scheme: \special{psfile="filename"[ key=value]*} This will download the POSTSCRIPT file called _f_i_l_e_n_a_m_e such that the current point will be the origin of the POSTSCRIPT coordinate system. If the _f_i_l_e_n_a_m_e string begins with the ` (grave accent) character then the remainder of the _f_i_l_e_n_a_m_e field is treated as a Unix Bourne shell script to be exe- cuted with its _s_y_s_o_u_t down loaded as a POSTSCRIPT file. For example: \special{psfile="`zcat packed.ps" ...} will uncompress the file _p_a_c_k_e_d._p_s._Z for inclusion in ddvviippss output. The optional key/value assignments allow you to specify transformations on the POSTSCRIPT in _f_i_l_e_n_a_m_e. The possible keys are: hoffset The horizontal offset (default 0) voffset The vertical offset (default 0) hsize The horizontal clipping size (default 612) vsize The vertical clipping size (default 792) hscale The horizontal scaling factor (default 100) vscale The vertical scaling factor (default 100) angle The rotation (default 0) The hoffset, voffset, hsize, and vsize are given in POSTSCRIPT units (1/72 of an inch), called bp elsewhere in TeX; these are the units of the default coordinate system assumed to be valid in the POSTSCRIPT file. The hscale and vscale are given in non-dimensioned percentage units, and the rotate value is specified in degrees. Thus \special{psfile=foo.ps hoffset=72 hscale=90 vscale=90} will shift the graphics produced by file _f_o_o._p_s right by 1", and will draw it at 0.9 normal size. If either hsize or vsize is specified, the figure will be clipped to a TeXware 9 August 1990 8 DVIPS User Commands DVIPS rectangular region from (0,0) to (hsize,vsize) in default coordinates, after scaling, translation, and/or rotation. Otherwise no clipping will be done. Offsets are given rela- tive to the point of the \special command, and are unaf- fected by scaling or rotation. Rotation is counterclockwise about (0,0). The order of operations is: Take the POSTSCRIPT figure, rotate it, then scale it, then offset it, then clip it. For example, if you want to extract a one-inch-square figure bounded by (100,200), (172,200), (172,272), and (100,272) in the POSTSCRIPT coordinates of the graphic in cropthis.ps, you would say \special{psfile=cropthis.ps hoffset=-100 yoffset=-200 hsize=72 vsize=72} Secondly, if your file conforms to the _E_n_c_a_p_s_u_l_a_t_e_d _P_o_s_t _S_c_r_i_p_t (EPS) conventions, then it is possible to use a simpler \\ssppeecciiaall command that will automatically reserve the required space. To use, simply say \input epsf % at the beginning of your TeX document \epsfbox{filename.ps} % at the place where you want the figure A _v_b_o_x of the appropriate size for the bounding box will be built. The height and width of this vbox will be the height and width of the figure; the depth of the vbox will be zero. By default, the graphic will have its `natural' width. If you wish to enlarge or reduce it, simply set the dimension `\epsfxsize' to something else, such as `\hsize'; the figure will be scaled so that \epsfxsize is its final width. A more general facility for sizing is available by defining the `\epsfsize' macro. This macro is used to give \epsfx- size a value each time \epsffile is called. It takes two parameters; the first is the horizontal natural size of the POSTSCRIPT figure, and the second is the vertical natural size. (Natural size, in this case, is the size in POSTSCRIPT points from the bounding box comment.) The default definition of this macro is \def\epsfsize#1#2{\epsfxsize} which just means to take the value that was set before the macro was invoked. Note that the variable \epsfxsize is reset to zero at the end of each call to \epsffile. You can redefine this macro to do almost anything. It must return the xsize to use, or 0 if natural scaling is to be used. Common uses include: \epsfxsize % just leave the old value alone TeXware 9 August 1990 9 DVIPS User Commands DVIPS 0pt % use the natural sizes #1 % use the natural sizes \hsize % scale to full width 0.5#1 % scale to 50% of natural size \ifnum#1>\hsize\hsize\else#1\fi % smaller of natural, hsize The resultant vbox can be centered with \centerline, or treated as any other vbox. If you are using LaTeX and the center environment, be sure to execute a \leavevmode before each use of \epsffile, so that LaTeX leaves the vertical mode and enters the paragraph making mode. (This should probably be provided by the LaTeX macros themselves.) (The \epsfbox macro does its job by scanning filename.ps for a standard `BoundingBox' comment. The figure is clipped to the size of that bounding box. If the bounding box is not found, a bounding box of `72 72 540 720' is assumed. If the POSTSCRIPT file to be included is not EPSF, you are probably better off using the _p_s_f_i_l_e special instead.) Thirdly, there are special commands for drawing diagrams using the conventions of `TPIC' (a portable, non-POSTSCRIPT-dependent program by Tim Morgan, with POSTSCRIPT implementation by Dorab Patel). For example, `\special{pn 2}' in this language sets the pen size to .002 inch. A fourth type of \special allows you to write POSTSCRIPT instructions that will be passed literally to dvips's output file. These are intended for people whose favorite graphics language is raw POSTSCRIPT. \special{" _t_e_x_t} includes _t_e_x_t literally in the output POSTSCRIPT document, after translating the origin to the current page position, opening a special user dictionary, and and reverting to the POSTSCRIPT convention of 72 units=1in. \special{! _t_e_x_t} includes _t_e_x_t literally in the prolog (before all typeset- ting is done), putting definitions in the special diction- ary; this is good for definitions you intend to use with \special{"}. Note that _d_v_i_p_s will always include such spe- cials in the prolog, unless they occur on pages after the last page printed. This allows correct printing of selected pages, even when literal POSTSCRIPT definitions are used, provided that you give definitions before their first use. A fifth type of \special allows literal POSTSCRIPT instruc- tions to be inserted _w_i_t_h_o_u_t enclosing them in an invisible TeXware 9 August 1990 10 DVIPS User Commands DVIPS protective shield; users of this feature are supposed to understand what they are doing (and they shouldn't change the POSTSCRIPT graphics state unless they are willing to take the consequences). This command can take many forms, because it has had a tortuous history; any of the following will work: \special{ps:_t_e_x_t} \special{ps::_t_e_x_t} \special{ps::[begin]_t_e_x_t} \special{ps::[end]_t_e_x_t} (with longer forms taking precedence over shorter forms, when they are used). Exception: The command \special{ps: plotfile _f_i_l_e_n_a_m_e} will copy the commands from _f_i_l_e_n_a_m_e verbatim into dvips's output (but omitting lines that begin with %). An example of the proper use of literal specials can be found in the file rroottaattee..tteexx,, which makes it easy to typeset text turned 90 degrees. Finally, there are two special cases of \special, which pro- vide alternatives to certain dvips command-line options: (1) You may put the command \\ssppeecciiaall{{llaannddssccaappee}} anywhere in your document (except after the final page selected for printing), and the entire document will be printed in landscape mode. (2) The command \\ssppeecciiaall{{hheeaaddeerr==_f_i_l_e_n_a_m_e}} may be used to add _f_i_l_e_n_a_m_e as a header file (i.e., a file that will be downloaded before the start of processing). This is usually used for Macintosh header files. The header file will be added to the POSTSCRIPT userdict. For special effects, if any of the macros _b_o_p-_h_o_o_k, _e_o_p-_h_o_o_k, _s_t_a_r_t-_h_o_o_k, or _e_n_d-_h_o_o_k are defined in the POSTSCRIPT userdict, they will be executed at the beginning of a page, end of a page, start of the document, and end of a document, respectively. When these macros are executed, the default POSTSCRIPT coordinate system is in effect. Such macros can be defined in headers added by the --hh option or the hheeaaddeerr== special, and might be useful for writing, for instance, DRAFT across the entire page, or, with the aid of a shell script, dating the document. These macros are exe- cuted outside of the save/restore context of the individual pages, so it is possible for them to accumulate information, TeXware 9 August 1990 11 DVIPS User Commands DVIPS but if a document must be divided into sections because of memory constraints, such added information will be lost across section breaks. Several of the above tricks can be used nicely together. For instance, a --PP file can be set up to print the date on each page; the particular configuration file will execute a command to put the date into a header file, which is then included with a hh line in the configuration file. Note that multiple --PP options can be used. If the filename in any of the POSTSCRIPT inclusion options begins with a backtick, that name is interpreted instead as a command to be executed to generate the appropriate file. The POSTSCRIPT must be generated to standard output by the command. This is useful, for instance, for uncompressing large POSTSCRIPT files using zcat. FFIILLEESS For more information, see the manual dvips.tex distributed with the program. Files used by dvips are usually system dependent, but the following are typical: the prolog dir /usr/lib/tex/ps the config dir /usr/lib/tex/ps the tfm dir /usr/lib/tex/fonts/tfm the font dir /usr/lib/tex/fonts/pk the virtual font dir /usr/lib/tex/fonts/vf the epsf/psfile dir .:..:/usr/lib/tex/inputs SSEEEE AALLSSOO mf(1), afm2tfm(1), tex(1), latex(1), lpr(1) NNOOTTEESS POSTSCRIPT is a registered trademark of Adobe Systems Incor- porated. AAUUTTHHOORR Tomas Rokicki <rokicki@neon.stanford.edu>; extended to vir- tual fonts by Don Knuth. TeXware 9 August 1990 12